Node3D plugin example

This example shows how to create a custom 3D node and how to use that node in Kanzi Studio through the Kanzi Engine plugin system. The Kanzi example contains a Visual Studio solution that defines the .dll for the plugin where the custom nodes are created, and a Kanzi Studio project that uses the plugin system to apply in the Kanzi Studio Preview the behaviors defined in the custom nodes.

You can find the example in <KanziWorkspace>/Examples/Node3D_plugin.

Creating custom nodes

The two custom nodes in the example are:

• Knob reacts to user input by sending messages about the current rotation angle of the knob. It generates its own messages based on the user input (pan gestures). Knob generates these message types intercepted in Kanzi Studio at the Knob:
  • Rotation of the knob is forwarded to the external visualization of the knob by passing the argument directly to its Z-rotation attribute.
  • Discrete level updates are treated by generating application events (also messages), which are passed to the Spinner node.
• Spinner reacts to messages by updating the Text property of the Text Block node, to show the value from the Knob. It receives messages from the outside and reacts to the messages based on its own defined behavior.

Kanzi Studio reads the information about the messages and property types used by the custom nodes from the plugin .dll.

Kanzi Engine registers the plugin by calling a function with this signature from the plugin

extern "C"
{
	__declspec(dllexport) Module* createModule(uint32_t kanziVersionMajor, uint32_t kanziVersionMinor);
}

Knob and Spinner nodes are registered in the getMetaclassesOverride() function which is defined in the module that you create and that the createModule() function returns.

In order to register the Spinner node, the Spinner must contain a metaclass. By using the KZ_METACLASS_BEGIN you define a custom node and there you declare:

• Base class (Node3D)
• Unique ID ("Spinner")
• Messages it uses (SpinnerUpdateLevelMessage)
• Property types it uses (TextBlockProperty)

KZ_METACLASS_BEGIN(Spinner, Node3D, "Spinner");
	KZ_METACLASS_MESSAGE_TYPE(SpinnerUpdateLevelMessage)
	KZ_METACLASS_PROPERTY_TYPE(TextBlockProperty)
KZ_METACLASS_END();

In this example the Spinner creates its message type SpinnerUpdateLevelMessage by specifying that it uses SpinnerUpdateLevelMessageArguments.

// The message name must be unique. In this case "Message.Spinner.UpdateLevel".
// And you must specify the routing type for the message. In this case
// KZU_MESSAGE_ROUTING_TUNNELLING_BUBBLING.
MessageType<Spinner::SpinnerUpdateLevelMessageArguments>
	Spinner::SpinnerUpdateLevelMessage("Message.Spinner.UpdateLevel", KZU_MESSAGE_ROUTING_TUNNELLING_BUBBLING);

In order to register the message arguments for the SpinnerUpdateLevelMessage the SpinnerUpdateLevelMessageArguments must contain the metaclass that defines the message arguments. By using the KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN you define the argument for the custom message and there you declare:

• Base class (MessageArguments)
• Unique ID ("Spinner Update Level Message Arguments")
• Property type (SpinnerLevelAlterationProperty)

KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(SpinnerUpdateLevelMessageArguments, MessageArguments, "Spinner Update Level Message Arguments")
	KZ_METACLASS_PROPERTY_TYPE(SpinnerLevelAlterationProperty)
KZ_METACLASS_END()

Building the plugin .dll

To build the plugin .dll that the example uses:

1. In Visual Studio 2010 open the solution for the example <KanziWorkspace>/Examples/Node3D_plugin/Application/configs/platforms/win32.
2. In Visual Studio select the GL_vs2010_Debug_DLL solution configuration.
   
3. Build the Node3D_plugin application.
   When Visual Studio completes the building, it places the plugin .dll to <KanziWorkspace>/Examples/Node3D_plugin/Application/output/win32/GL_vs2010_Debug_DLL. This is also the location where the Node3D_plugin example Kanzi Studio project is configured to look for the plugin.
   

4. Make sure that the solution configuration you used in Visual Studio to build your application and plugin projects matches the settings of your Kanzi Studio project.
   For example, if you used the GL_vs2010_Debug solution in Visual Studio, in your Kanzi Studio project in the Project > Properties set:

   • Preview OpenGL ES Wrapper to GL (Emulation through desktop OpenGL)
   • Preview Build Configuration to Debug
   • Preview Visual Studio Version to 2010

   

5. In Kanzi Studio start the Preview. When the Preview starts, it loads the plugin .dll you built and you can interact in the Preview with the custom components defined in the application code.

See also

Kanzi Engine plugins

Examples

Open topic with navigation